Skip to content

Automate rustc(1) man page generation using help2man script #150066

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
jkelley129 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Automate rustc(1) man page generation using help2man script #150066

jkelley129 wants to merge 2 commits into from
+90 −0

Conversation

@jkelley129
Copy link

@jkelley129 jkelley129 commented Dec 16, 2025

Summary

This PR introduces a reproducible and automated process for generating the rustc(1) man page directly from the compiler’s help output, ensuring it always reflects the current CLI.

Details

  • Adds src/doc/man/generate-rustc-man.sh:
    A shell script that invokes help2man on any given rustc binary, via that binary’s --help -v output.

    • Produces src/doc/man/rustc.1
    • Script is robust to execution directory and always writes to the correct location.

  • Documentation in src/doc/man/README.md:

    • Explains the motivation, the step-by-step usage, prerequisites, and the rationale for making the man page solely reflect the actual compiler binary.
    • Documents command usage and expectations.

Rationale

  • Source of Truth:
    The man page is generated entirely from the compiler’s current help text, eliminating drift between documentation and reality.
  • Reproducible:
    The script ensures anyone can regenerate the man page exactly, as long as they have a target compiler binary and help2man installed.
  • Minimal coupling:
    By keeping the script and artifacts local to src/doc/man, there’s no need to depend on build system internals.

Usage

After building rustc, simply run:

./src/doc/man/generate-rustc-man.sh path/to/rustc
  • Requires help2man on the host system (apt install help2man, dnf install help2man, etc).

Notes

  • No changes are made to core Rust sources.
  • The man page should be regenerated if any CLI options/output are changed in the future.

Ready for feedback or further suggestions!

@jkelley129
Generate rustc.1 man file from rustc --help output using help2man
6257a2d 
Generate the rustc.1 man page from `rustc --help -v` using help2man
to ensure the documentation stays in sync with the compiler’s actual
CLI behavior.

The generation logic lives in src/doc/man and writes rustc.1 to the
same directory, independent of the current working directory.
@jkelley129
Add reproducible man page generation for rustc using help2man
54efbdc 
- Introduce `src/doc/man/generate-rustc-man.sh`, a robust script that generates the `rustc(1)` man page entirely from the current built binary’s `--help -v` output using help2man.
- Add `README.md` in the same directory to document the rationale, instructions, and prerequisites for this process.
- Ensures the man page always reflects the actual compiler behavior, avoids manual edits or duplication, and is easy to update as CLI options evolve.
@rustbot rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Dec 16, 2025
@rustbot
Copy link
Collaborator

rustbot commented Dec 16, 2025

r? @GuillaumeGomez

rustbot has assigned @GuillaumeGomez.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

@GuillaumeGomez
Copy link
Member

GuillaumeGomez commented Dec 16, 2025

Not too sure who's supposed to review this.

r? compiler

@rustbot rustbot added the T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. label Dec 16, 2025
@rustbot rustbot assigned SparrowLii and unassigned GuillaumeGomez Dec 16, 2025
@Kivooeo
Copy link
Member

Kivooeo commented Dec 16, 2025

I’m a bit unsure how to route and review this change, since it was redirected to a compiler team. As far as I understand it introduces new documentation-generation tooling and touches on how the rustc(1) man page is produced, and it’s not clear to me which team should be reviewing this or how it fits into our existing documentation processes

Could you clarify:

  • what problem this is intended to solve in the context of the current rustc documentation workflow?

  • whether this is meant as a proposal/experiment, or something you expect to be adopted as-is?

That would help figure out how (and by whom) this should be discussed further

@jkelley129
Copy link
Author

jkelley129 commented Dec 16, 2025

I noticed two different issues(#149875 and #98977) that mentioned the rustc man page being out of sync with the rustc --help output, and they both suggested using an script to generate the man page from the help output to keep documentation in sync. This PR was meant to be an implementation of that. I am open to any modifications or suggestions to the implementation or to make it fit better into the current documentation workflow.

I apologize for not linking the issues initially, that may have made it more clear.

@jyn514
Copy link
Member

jyn514 commented Dec 17, 2025 •
edited
Loading

@Kivooeo i’m willing to review this if you can’t find a reviewer. i don’t have r+ permissions anymore though.

@Kivooeo
Copy link
Member

Kivooeo commented Dec 17, 2025 •
edited
Loading

@Kivooeo i’m willing to review this if you can’t find a reviewer

Yeah, that's sounds really nice, thanks for taking time on it

also if you know, because I don't if we have to cooperate this with our release or infra teams to integrate this into our release process, like generate man before/with new release or only after editing cli flags, you might know this better

i don’t have r+ permissions anymore though.

Also not a problem

Do "r=me,jyn514" after approval, I'd only ask to be impartial as you can (for example README here is obviously written by ai, I'd prefer to see something more human if you share this. If it's important to clarify, I'm not writing this to criticize the author, but rather as something that could be improved, nothing personal)

r? jyn514

@rustbot rustbot assigned jyn514 and unassigned SparrowLii Dec 17, 2025
@rustbot
Copy link
Collaborator

rustbot commented Dec 17, 2025

jyn514 is not on the review rotation at the moment.
They may take a while to respond.

@Kivooeo
Copy link
Member

Kivooeo commented Dec 17, 2025

@bors delegate=jyn514

@bors
Copy link
Collaborator

bors commented Dec 17, 2025

✌️ @jyn514, you can now approve this pull request!

If @Kivooeo told you to "r=me" after making some further change, please make that change, then do @bors r=@Kivooeo

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@jyn514 jyn514

Labels

S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

7 participants

@jkelley129 @rustbot @GuillaumeGomez @Kivooeo @jyn514 @bors @SparrowLii